home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
User's Choice Windows CD
/
User's Choice Windows CD (CMS Software)(1993).iso
/
win_i_l
/
incx101b.zip
/
INC-PROG.LZH
/
HELP.LZH
/
MCAEL.HLP
< prev
next >
Wrap
Text File
|
1991-07-26
|
39KB
|
700 lines
mcael
Help information about: InContext Procedure Language
E╔════════════════════════════════════════════════╗
E║ CInContext Procedure LanguageE ║
E╚════════════════════════════════════════════════╝
CA Word to the Wise...
If you can write MS-DOS batch procedures, you should have no difficulty
learning to use the InContext Procedure Language. If "batch files" are
beyond your present capability, though, then you may want to learn about
them before you undertake to write your own InContext procedures. You
should find the information you need in your MS-DOS User Guide.
The procedures you write here will usually be based on MS-DOS commands,
with some notable assistance from a few special commands made available by
InContext. Programming, particularly of the "batch file" sort, is really
not very difficult, and there's no reason to be intimidated by it. It
should not be done carelessly, though, since it is possible to
inadvertently modify, or even delete, files. Current backups of your
files can be a real lifesaver, whether you're testing out new procedures
or not, but they're especially wise in such a case.
You may find it helpful to F ªPDrint B this information, for easy reference.
CHow InContext Procedures Work
A CprocedureB is a list of commands that are executed when:
ZmcaB CB an CactionB is selected (see CJ Actions CB).
ZmcdB CB an item from the CdoB list is selected (see CJ The Do Command CB).
The CcommandsB in a procedure consist of some mixture of CMS-DOS commands
and Cinternal InContext commandsB. You are assumed to be familiar with the
common MS-DOS commands, such as "echo", "copy", "move", etc., and we will
also refer to the invocation of other programs as a use of "MS-DOS
commands", since they are invoked by asking MS-DOS to execute them.
Obviously, though, the InContext commands are unfamiliar, and they will be
discussed in detail below.
When a procedure is executed, the commands are executed in sequence,
starting at the top (except as this may be altered by MS-DOS CgotoB, and
InContext CmenuB and CforEachObjectB commands). The internal commands are
simply executed by InContext when it reaches them. MS-DOS commands have
to be passed to the MS-DOS command processor, though. (Normally, this
is the program "command.com", but some users substitute an alternative
command processor.)
If several consecutive lines of a procedure are MS-DOS commands, they are
passed to the command processor by writing them out as an MS-DOS batch
file and arranging for the command interpreter to execute the batch file.
If an MS-DOS command occurs alone in a procedure, or is surrounded by
internal commands, it is passed directly to the command processor without
being written to a batch file. Since there is some overhead associated
with invoking the command processor, you can see that CunnecessaryB
alternation between MS-DOS commands and internal commands would impede
performance.
If an error occurs during execution of a procedure, InContext will display
the error message and halt execution of the procedure. Please note that
InContext has no direct way of knowing about errors that may have occurred
during the execution of other programs (command.com does not return the
ERRORLEVEL value that is available for testing within batch files). The
only errors that can be directly detected by InContext are errors in the
execution of its internal commands. For this reason, if for no other, you
should probably use the CinternalB versions of such commands as copy,
delete, etc.
CSwapping InContext Out of Main Memory
Whenever the MS-DOS command processor is invoked to execute an MS-DOS
command or another program, part of the InContext program and data are
"swapped out". That is, a portion of InContext is written out to either
EMS memory or to disk, in order to make room for the (possibly large)
program that is being invoked. You can control how this swapping occurs,
and how much memory is freed. This is done globally by setting the
ZmcmoeB appropriate configuration options (see CJ MS-DOS Command Execution CB),
and locally by the CmemoryB command (see below).
CA Small Example
The following example is a little contrived, for which we apologize. Most
actions require only a one-line procedure, and we need an example here
that will illustrate a bit more than those actions would allow.
Let's suppose that you have a spelling-checker program called "spellit",
which scans an ASCII text file, noticing words that don't match any entry
in the program's dictionary. Assume that the program prompts the user for
corrections in such a case, and rewrites the file, with spelling
corrections, on exit. Let's suppose that it also updates its own
dictionary if you give it new words during an execution, and that the
dictionary is kept in the directory "c:\mystuff". Finally, let's
assume that spellit requires no more than 256K (256 kilobytes of main
memory) to run. If we would like to add a "spell-chk" action for objects
of the "txt" class.
An acceptable procedure for such an action might be simply
spellit %f
where the characters "%f" will be replaced by the filename of the selected
text object. A more complete procedure, though, might be
!memory 256
spellit %f
!relogDir c:\mystuff
This procedure illustrates the use of both internal commands and MS-DOS
commands. The commands preceded by exclamation points (C!B) are internal
InContext commands. The first command ("!memory 256") directs InContext
to swap out only enough of itself to provide 256K of memory for the
following MS-DOS process. The second command ("spellit %f") executes
spellit on the selected object. The third ("!relogDir c:\mystuff") causes
InContext to update its record of the contents of the directory
c:\mystuff, so that it will reflect the modified size, date, etc. of the
dictionary file.
CVariable Substitution
One thing you need to know more about is variable substitution. During
the execution of procedures, InContext looks for a set of one-character
"variable names", each of which is preceded by the percent (C%B) character.
Whenever one of these variable names is encountered, it is replaced by an
appropriate value before the command is executed. For example, if the
currently selected object is "mystuff.txt", then the command
myeditor %f
becomes
myeditor mystuff.txt
before it is passed to MS-DOS for execution.
The InContext variables are:
C%cB The CclassB of the currently selected object
C%dB The full pathname of the currently selected Cdirectory
C%DB The current Cdate
C%fB The CfilenameB of the currently selected object
C%hB The Cfull pathnameB of the currently selected object
C%kB The name of the currently selected CtaskB
C%KB The CdescriptionB of the currently selected task
C%lB The number of ClinesB currently on the video display
C%mB For use only in the group action list, the CmultipleB filespec that
describes the currently displayed objects. This might be
replaced by "*.*", if the "ALL" view is selected, or by "*.txt",
if only the text class is selected, or by "*.doc *.txt" if a view
containing both "doc" and "txt" classes is selected.
C%pB The filename CprefixB of the currently selected object
C%TB The current Ctime
C%uB The name of the current CuserB of InContext
The following additional variables are related to the "query" command.
C%1B The current value of variable 1
C%2B The current value of variable 2
C%3B The current value of variable 3
C%4B The current value of variable 4
C%5B The current value of variable 5
C%6B The current value of variable 6
C%7B The current value of variable 7
C%8B The current value of variable 8
C%9B The current value of variable 9
The following additional variables have meaning only when executing a
"forEachObject" loop:
C%CB The class of the current object
C%FB The filename of the current object
C%HB The full pathname of the current object
C%PB The filename prefix of the current object
CMacros
The use of Macros is common in programming languages at all levels, and
it can greatly increase power and reuseability of procedures. For
ZmcaemB information, see CJ Macro Action Definitions CB),
Macros in procedures are indicated by the use of the pound sign (C#B) as the
first character of the line. Thus, a common way of invoking the user's
preferred text editor is
#editText
where the "editText" macro contains the detailed command(s) necessary
to invoke the editor in the desired manner.
CInContext Internal Commands
The internal commands are listed below, along with descriptions and, where
appropriate, examples. For any commands that take arguments, the syntax
of the command is also shown. In syntax descriptions, everything shown
in CboldB text must appear as shown, while everything shown in ordinary
text is a placeholder. Optional information is surrounded by square
brackets. Thus, the description:
CdeleteB [ filename ] [ CnoqueryB ]
indicates that the delete command takes two optional arguments, one of
which is a filename and the other of which is the string "noquery".
The internal commands you would ordinarily use are:
CchangeDirB This command changes the current working
directory to a specified directory. The chosen
directory will remain the current working directory
until the next "changeDir" command, or the next
MS-DOS "cd" command, or the end of the procedure.
This command is equivalent to the MS-DOS "cd" command
except that it can cause a change in drive, as well
as directory. Syntax is:
CchangeDirB pathOfNewDir
Thus, to change to the "temp" directory on the "d:"
drive, the command would be
changeDir d:\temp
Use of this command is preferable to the MS-DOS "cd"
command, because InContext will be aware of the
working directory, and will therefore automatically
relog the directory.
CchoiceB See "menu".
CcopyB This command exhibits two different kinds of
behavior, depending on the arguments used.
Syntax is:
CcopyB [ source destination [ CnoqueryB ] ]
If no arguments are used, as in
copy
the command prompts the user for the name (or
possibly directory or full path) to which the
selected object should be copied. If the user
responds with such a name or path, the copy operation
is executed.
Alternatively, if source and destination pathnames
are given, the indicated source file is copied to
the indicated destination. The source must indicate
an existing file, and may be a simple filename, if
the file is in the current directory, or a complete
pathname. The destination can be a simple filename
or a full pathname. If the destination is found to
be a directory, a new copy of the source will be
placed in the destination directory, using the source
filename. Otherwise, a new copy of the source file
will be created and given the destination filename.
If there is already a file using the destination
name, the user will be asked for permission before
copying occurs, unless the "noquery" argument is
present. Thus, the command
copy myfile.txt a:\ noquery
would copy "myfile.txt" to the root directory of the
A: drive, and would not ask permission before over-
writing a file of the same name there.
CcreateObjectB This command creates a new object, based on the
filename prefix and class specified in the command.
Syntax is:
CcreateObjectB prefix class
Thus, the command "createObject mynext doc" would
create the object "mynext.doc" in the current
directory.
CdeleteB This command deletes the specified object, or if
none is specified, deletes the currently selected
object. The user is asked for permission before
deletion, unless "noquery" is specified. Syntax is:
CdeleteB [ filename ] [ CnoqueryB ]
Thus, to delete the file "mytemp.txt", without asking
user permission, the command would be
delete mytemp.txt noquery
If the file does not exist, no deletion occurs and
no error is noted.
CeditB This command invokes the internal editor on the
specified file, if any, or on the currently selected
object, if no file was specified. Syntax is:
CeditB [ filename ]
CeditDictionaryB Some of the files used by InContext are
"dictionary" files (class "dic"). The internal
dictionary editor is made available for use on such
objects by this command. You might use this command
to create dictionary files for use with the "info"
command (see below). Syntax is:
CeditDictionaryB [ filename ]
CendForB See "forEachObject".
CendMenuB See "menu".
CforEachObjectB This command allows you to execute a portion of
a procedure once for each object currently being
displayed. You might use it if you have a program
that only operates on one file at a time, but you
want to be able to invoke it on a whole class or
view. If the program is question is "theprog", the
commands required would be:
!forEachObject
theprog %F
!endFor
Notice that the "endFor" command is also required,
and that it indicates the end of the loop that will
be executed once for each object. Notice also that
the special variable names %F, %H, %C, and %P must be
used instead of %f, %h, %c, and %p.
CinfoB This command allows you to display a scrollable
window containing text you have written. It is
useful for providing explanations of a procedure
during its execution. Syntax is:
CinfoB dictionaryPath term [ title ]
The information displayed will be the definition of
the specified term, taken from the dictionary ("dic"
object) whose full MS-DOS pathname is specified.
If you provide a title, that title will be displayed,
as well. For example, to display information at the
beginning of a Do procedure that downloads stock
prices, you might use the command:
info c:\incontxt\myinfo.dic getprice
CkeyStuffB This command allows you to place information in the
keyboard buffer before calling an application.
Suppose, for example, you have a word processor that
doesn't allow you to specify a filename on the
command line, but expects you to select a "file load"
command after you're in the program. You might use a
command sequence like:
!keyStuff "FL%f\EN"
myWordProc
to cause it to automatically load the selected object
upon entry. The !keyStuff command loads the keyboard
buffer with the command characters 'F' and 'L',
followed by the filename of the currently selected
object, followed by the ENTER key. Those characters
will then be read by the program "myWordProc" as if
they had been typed from the keyboard after the
program was invoked. This will not work with ALL
programs, but works with most. This feature greatly
increases your ability to "encapsulate" applications
with InContext.
There are a number of special characters that can be
loaded into the keyboard buffer using this technique.
An example is the ENTER key designated by the "\EN"
in the example above. These special characters are
all indicated by a backslash and a two-character code
that represents the special character. The codes are
as follows:
For Cfunction keysB, the code consists of the
character "F", followed by a numeric digit from
1 through 0. These correspond to function keys
F1 through F10. "\FA" also means F10, and
"FB" and "FC" correspond to F11 and F12 on the
extended keyboard. (The hexadecimal symbols for
10, 11, and 12 are A, B, and C, respectively.)
If Cshifted function keysB are desired, the codes
are "\S1" through "\S0" and "\SA" through "\SC".
CControl-function-keyB combinations are obtained
by "\C1" through "C0" and "\CA" through "\CC".
CAlt-function-keyB combinations are "\A1" through
"\A0" and "\AA" through "\AC".
Ordinary Ccontrol charactersB, such as control-A,
use codes beginning with '^'. Thus, "\^A"
through "\^Z" mean control-A through control-Z,
and control-key versions of the following
additional characters can be created this way:
[ \ ] ^ _ @
Ordinary Calt-key charactersB, such as alt-A,
use codes beginning with '@'. Thus, "\@A"
through "\@Z" mean alt-A through alt-Z,
and alt-key versions of the following
additional characters can be created this way:
numeric digits, -, =
All remaining Cspecial charactersB are shown in
the following table:
LA left arrow
LC control left arrow
RA right arrow
RC control right arrow
UA up arrow
UC control up arrow
DA down arrow
DC control down arrow
HM home
HC control home
ED end
EC control end
PU page up
QU control page up
PD page down
QD control page down
IN insert
DE delete
G+ grey +
G- grey -
G* grey *
PS PrtSc
PC control PrtSc
TA tab
BT back tab
ES escape
BS back space
EN ENTER (carriage return)
LF line feed
N0 numeric key-pad 0
N1 numeric key-pad 1
N2 numeric key-pad 2
N3 numeric key-pad 3
N4 numeric key-pad 4
N5 numeric key-pad 5
N6 numeric key-pad 6
N7 numeric key-pad 7
N8 numeric key-pad 8
N9 numeric key-pad 9
N. numeric key-pad .
N+ numeric key-pad +
N- numeric key-pad -
N* numeric key-pad *
To stuff the backslash character into the buffer, use
two backslashes in succession, as "\\".
In the current version of InContext, the string that
is loaded by "!keyStuff" is restricted to 15
characters. This will be extended in a later
version.
Incidentally, whenever InContext executes another
program, it clears the keyboard buffer on return.
This prevents unprocessed keystrokes from doing
unexpected things upon return to InContext. However,
if the "!keyStuff" command is used and not followed
by the execution of another program, the keystrokes
are left in the buffer and read by InContext as if
you had typed them in yourself. This allows you to
define procedures that exert user-level control over
InContext, if you like. This is recommended for
knowledgable users only.
An especially useful application of the latter is in
an InContext startup ("incStart") macro. By placing
in that macro, for example,
!keyStuff "df"
it is possible to cause the automatic execution of
a Do procedure (e.g., "fontset") at InContext
initialization time.
CmemoryB This command allows you to specify the amount of
memory needed for the next following block of MS-DOS
commands. You can optimize InContext performance by
requesting only what is actually needed, if you
choose to do so. Syntax is:
CmemoryB kilobytes
Thus, to invoke a simple word-count program that
needs only 64K of memory, you might use the commands
!memory 64
wc %f
CmenuB This command allows you to construct menus within
a procedure. Syntax is:
CmenuB [ title ]
This command is used with a series of "choice"
commands and an "endMenu" command, to specify a whole
menu and the consequences of each possible choice.
A simple example is:
!menu "Do which simple MS-DOS operation?"
!choice "Check disk"
chkdsk
!choice "Show directory contents"
dir
!endMenu
Menus may not be nested (but notice that that
probably isn't necessary, given that the menus occur
in the context of actions that are themselves menu-
selected).
CnoRelogB This command can be used to slightly speed up
the return of InContext after a procedure, if you
know that the procedure cannot alter any files.
By letting InContext know that the files cannot be
altered, you eliminate the need for relogging the
files in the current directory upon return from the
procedure. This command can occur anywhere in the
procedure. A common example would be the use of a
viewer:
!noRelog
pcxview %f
CpauseB This command causes InContext to pause, and wait
for a keystroke or mouse key depression. It is used
immediately after a DOS command or external program
in order to allow the user to look at the results of
that operation before returning to InContext.
CqueryB This command allows you to ask the user for
information, and then to use the information in
subsequent commands in the procedure. Syntax is:
CqueryB variable question length
InContext provides nine variables whose values can
be set by query commands. The first argument is the
number of the variable that will contain the user's
answer. The second argument is the text of a
question that will be asked. The third argument is
the length, in characters, of the answer field.
At the risk of waxing a little fanciful, suppose you
have a program, "coatarms" that displays a coat of
arms for the user's family, given his family name.
You might write:
!query 3 "Enter your last name" 20
coatarms %3
If the user answers "Smith", this would result in
the actual execution of the command "coatarms Smith".
CrelogDirB Unless you use the "noRelog" command, InContext
always checks all the files in the current directory
at the end of each procedure, to make sure that its
object list is up-do-date. It does CnotB automatically
relog other directories, however. If you execute a
program that is known to modify the contents of some
other directory, you can cause InContext to update
the log for that directory as well, by use of the
"relogDir" command. Syntax is:
CrelogDirB pathOfDirectory
For example, if your editor automatically backs up
all files to the directory "c:\backup", and you want
the object list to be current whenever you go to that
directory, you might use the sequence
myeditor %f
!relogDir c:\backup
to invoke your editor.
CrenameB This command exhibits two different kinds of
behavior, depending on the arguments used.
Syntax is:
CrenameB [ source destination [ CnoqueryB ] ]
If no arguments are used, as in
rename
the command prompts the user for the new name for
the selected object. This may be a simple filename
or a full pathname (this command can be used to move
the selected object to another directory, or even
another drive). If the user responds with such a
name, the object is moved and/or renamed, as
appropriate.
Alternatively, if source and destination pathnames
are given, the indicated source file is moved to
the indicated destination. The source must indicate
an existing file, and may be a simple filename, if
the file is in the current directory, or a complete
pathname. The destination can be a simple filename
or a full pathname. If the destination is found to
be a directory, the source object will be placed in
the destination directory, using the source filename.
Otherwise, the source object will be given the
destination filename, and moved to the indicated
drive or directory if that information was included
in the destination.
If there is already a file using the destination
name, the user will be asked for permission before
renaming occurs, unless the "noquery" argument is
present. Thus, the command
rename myfile.txt a:\ noquery
would move "myfile.txt" to the root directory of the
A: drive, and would not ask permission before over-
writing a file of the same name there.
CresetMouseB Some programs which you may invoke from within
InContext disable the mouse and fail to restore it
upon exit. If you don't see a cursor upon return
from such a program, or if the mouse no longer works,
you should add the "resetMouse" command to the
procedure. On some machines, the mouse reset
operation adds a second or two to the time required
to return to InContext; that's why it isn't done
every time.
CunloadB A few memory-hungry applications may require more
memory for their execution than InContext can make
available by swapping itself to disk or EMS. A good
example is Ventura Publisher, if run on a machine
that doesn't have EMS memory. The "unload" command
can be used to cause InContext to write out the
desired MS-DOS commands to a batch file, and then
Cquit altogetherB, freeing CallB of the memory
used by InContext. Since the batch file is still
there, it can be executed from DOS.
When you installed InContext, you installed a batch
file, "inc.bat", which is used to execute InContext.
"inc.bat" checks, after each invocation of InContext,
to see if a procedure batch file has been left behind
for execution. If so, that batch file is executed
and InContext is reloaded.
You will only want to "unload" InContext in those few
cases that really need it, for performance reasons.
Note that, when "unload" is used, only the block of
MS-DOS commands immediately CfollowingB "unload" can
be executed. If you have any additional internal
commands after that block, they will not be executed.
CverifyB This command asks the user if it's OK to proceed,
and terminates the procedure if the user fails to
answer "Yes". Syntax is:
CverifyB [ question ]
If a question is specified, it is asked instead of
the default question. Thus, a possible form of this
command is
verify "Is it OK to archive this file?"
CviewB This command invokes the internal viewer on the
specified file, if any, or on the currently selected
object, if no file was specified. Syntax is:
CviewB [ filename ]
CviewArchiveB This command invokes the internal archive viewer
on the specified file, if any, or on the currently
selected object, if no file was specified. Syntax is:
CviewArchiveB type [ filename ]
The "type" argument can be any of the following, and
specifies both the archive file format and the
archiver program(s) to be used:
CACAB ARC format, using ARCA/ARCE.
CARCB ARC format, using SEA's ARC.
CARJB ARJ format, using ARJ.
CLZHB LZH format, using LHA.
CPAKB PAK format, using PAK.
CPKPB ARC format, using PKPAK/PKUNPAK
CZIPB ZIP format, using PKZIP/PKUNZIP.
For example, the following command would invoke the
archive viewer on an ARC-type document archive called
DOC-ARCV.XYZ, using the PKPAK/PKUNPAK programs for
any archive operations:
viewArchive PKP doc-arcv.xyz
CviewLZHB This command invokes the internal LHA viewer
on the specified file, if any, or on the currently
selected object, if no file was specified. Syntax is:
CviewLZHB [ filename ]
This command is now obsolete, and will not be
supported in future versions. Use "viewArchive LZH",
instead.
The following commands are also available, but you will ordinarily have
no need to use them in your own procedures:
CdeleteDirB If the current directory is empty and is not the
root directory of its drive, this command deletes the
directory and moves to the next directory above it.
CdeleteGroupB This command checks with the user first, and then
deletes each currently displayed object. Depending
on the user's choice, the objects can be deleted or
saved individually, or deleted as a group in a single
operation, or the command can be aborted.
CputB This command drops either a copy or the original
of an object being "carried" into the current
directory. The user is asked which is preferred.
This command is really only intended for internal
InContext use.
CtakeB This command causes InContext to "pick up" the
selected object, for possible later copying or moving
via the "put" command, above.
